package com.smaato;

/**
 * This class represents the Smaato Ad API. 
 * 
 * After instantiation, clients should 
 * (1) Optionally call one or more of the set methods to set optional parameters 
 * (2) Call getAd to trigger the download and processing of an Ad 
 * (3) On successful callback, call showAd which will return a SmaatoAd class containing the Ad image.
 */
public class SmaatoAPI 
{		
	/**
	 * No valid ads were returned by the service.
	 * 
	 * @see SmaatoAPICallback
	 */
	public static final int ErrNoValidAdsReturned 			= -2001;
	
	/**
	 * No content in the server response.
	 * 
	 * @see SmaatoAPICallback
	 */
	public static final int ErrNoContentInServerResponse 	= -2002;
	
	/**
	 * Error parsing the server response.
	 * 
	 * @see SmaatoAPICallback
	 */
	public static final int ErrParserError					= -2003;
	
	/**
	 * Error downloading ad image from server.
	 * 
	 * @see SmaatoAPICallback
	 */
	public static final int ErrDownloadAdFailed				= -2004;
	
	/**
	 * Error while creating text ad. The ad size was too small to render the text to.
	 * 
	 * @see SmaatoAPICallback
	 */
	public static final int ErrTextAdSize					= -2005;
	
	/**
	 * Error creating text ad image.
	 * 
	 * @see SmaatoAPICallback
	 */
	public static final int ErrAdCreation					= -2006;
		
	/**
	 * 	Valid Gender values, used in setGender.
	 *
	 */
	public static class Gender
	{
		public static final String 	Male = "m";
		public static final String 	Female = "f";
	}
	
	/**
	 * Valid Ad Format Values, used in constructor and setAdFormat.
	 *
	 */
	public static class AdFormat
	{
		public static final String  Image = "IMG";
		public static final String  Text = "TXT";
		public static final String  All = "ALL";
	}

	/**
	 * Valid Ethnicity values, used in setEthnicity.
	 *
	 */
	public static class Ethnicity
	{
		public static final String  White = "white";
		public static final String  MiddleEastern = "middleeastern";
		public static final String  Black = "black";
		public static final String  Latino = "latino";
		public static final String  SouthAsian = "southasian";
		public static final String  Oriental = "oriental";
		public static final String  Other = "other";
	}

	/**
	 * Valid Income values, used in setIncome.
	 *
	 */
	public static class Income
	{
		public static final String  LessThan15k = "lt15";
		public static final String  From15to24k = "15to24";
		public static final String  From25kto39k = "25to39";
		public static final String  From40kto59k = "40to59";
		public static final String  From60kto74k = "60to74";
		public static final String  From75kto99k = "75to99";
		public static final String  MoreThan100k = "mt100";
	}

	/**
	 * Valid Marital Status values, used in setMaritalStatus.
	 *
	 */
	public static class MaritalStatus
	{
		public static final String  Single = "s";
		public static final String  Divorced = "d";
		public static final String  Married = "m";
	}

	/**
	 * Valid Education values, used in setEducation.
	 *
	 */
	public static class Education
	{
		public static final String  LessThanSecondary = "ltsecondary";
		public static final String  Secondary = "secondary";
		public static final String  University = "university";
		public static final String  Advanced = "advanced";
	}

	/**
	 * Valid Gender Sought values, using in setGenderSought.
	 *
	 */
	public static class GenderSought
	{
		public static final String  Male = "m";
		public static final String  Female = "f";
		public static final String  Both = "b";
	}
	
	private SmaatoAPIImpl _impl;

	/**
	 * Constructs a new instance of the SmaatoAPI.
	 *  
	 * @param adSpace The adSpaceID to use
	 * @param publisher The publisherID to use
	 * @param adFormat The format of the ad to return
	 * @param getGPS true if the API should attempt to get GPS coordinates from the system.
	 */
	public SmaatoAPI(String adSpace, String publisher, String adFormat, boolean getGPS)
	{
		_impl = new SmaatoAPIImpl(adSpace, publisher, adFormat, getGPS);
	}
	
	/**
	 * Attempts to download an advert from the Smaato Service. The SmaatoAPICallback will be used 
	 * to notify success or failure.
	 * 
	 * @param aListener Will be notified on success or failure.
	 * @throws IllegalStateException if called while another call to getAd is still outstanding.
	 */
	public void getAd(SmaatoAPICallback aListener)
	{
		_impl.getAd(aListener);
	}
	
	/**
	 * Returns the Smaato Ad returned from the service. Success notification must be received before calling this method.
	 * 
	 * @return a valid SmaatoAd
	 * 
	 * @throws IllegalStateException if called before success has been notified.
	 */
	public SmaatoAd showAd()
	{
		return _impl.showAd();
	}
	
	/**
	 * Allows setting of Blackberry specific connection parameter to be appended to the end of the connection URL.
	 * 
	 * @param aConnectionParam a Blackberry specific connection parameter, can be null to clear field.
	 * @throws IllegalArgumentException if string length equals 0.
	 */
	public void setConnectionParameter(String aConnectionParam)
	{
		_impl.setConnectionParameter(aConnectionParam);
	}
	
	/**
	 * Sets the format of the requested ad.
	 * 
	 * @param adFormat must be a valid ad format from AdFormat class.
	 * @throws IllegalArgumentException if adFormat is null, length = 0, or adFormat is not a valid format
	 * @see AdFormat
	 */
	public void setAdFormat(String adFormat)
	{
		_impl.setAdFormat(adFormat);
	}
	
	/**
	 * Sets the height of the requested ad.
	 * 
	 * @param height the required height.
	 * @throws IllegalArgumentException if height is outside valid range (20 - 53)
	 */
	public void setHeight(int height)
	{
		_impl.setHeight(height);
	}
	
	/**
	 * Sets the width of the requested ad.
	 * 
	 * @param width the required width.
	 * @throws IllegalArgumentException if width is outside valid range (120 - 320)
	 */
	public void setWidth(int width)
	{
		_impl.setWidth(width);
	}
	
	/**
	 * Sets the background colour of a text ad (AdFormat equals Text).
	 * 
	 * @param color RGB colour in the format 0xRRGGBB (i.e. Red = 0xFF0000).
	 * @throws IllegalArgumentException if color is outside the range (0 - 0xFFFFFF)
	 */
	public void setTextAdBgColor(int color)
	{
		_impl.setTextAdBgColor(color);
	}
	
	/**
	 * Sets the text colour of a text ad (AdFormat equals Text).
	 * 
	 * @param color RGB colour in the format 0xRRGGBB (i.e. Red = 0xFF0000).
	 * @throws IllegalArgumentException if color is outside the range (0 - 0xFFFFFF)
	 */
	public void setTextAdFgColor(int color)
	{
		_impl.setTextAdFgColor(color);
	}
	
	/**
	 * Sets the users age.
	 * 
	 * @param age age.
	 * @throws IllegalArgumentException if age is less than 0.
	 */
	public void setAge(int age)
	{
		_impl.setAge(age);
	}
	
	/**
	 * Sets the users gender.
	 * 
	 * @param gender a valid gender value from Gender. null clears previously set parameter.
	 * @throws IllegalArgumentException if length = 0, or not a valid Gender value.
	 * @see Gender
	 */
	public void setGender(String gender)
	{
		_impl.setGender(gender);
	}
	
	/**
	 * Sets the users city.
	 * 
	 * @param city a city. null clears previously set parameter.
	 * @throws IllegalArgumentException length = 0.
	 */
	public void setCity(String city)
	{
		_impl.setCity(city);
	}
	
	/**
	 * Sets the users country.
	 * 
	 * @param country a country. null clears previously set parameter.
	 * @throws IllegalArgumentException if length = 0.
	 */
	public void setCountry(String country)
	{
		_impl.setCountry(country);
	}
	
	/**
	 * Sets the users state.
	 * 
	 * @param state a state. null clears previously set parameter.
	 * @throws IllegalArgumentException if length = 0;
	 */
	public void setState(String state)
	{
		_impl.setState(state);
	}
	
	/**
	 * Sets the users zip code.
	 * 
	 * @param zip a zip code. null clears previously set parameter.
	 * @throws IllegalArgumentException if length = 0.
	 */
	public void setZIP(String zip)
	{
		_impl.setZIP(zip);
	}
	
	/**
	 * Sets the users ethnicity.
	 * 
	 * @param ethnicity a valid ethnicity from Ethnicity. null clears previously set parameter.
	 * @throws IllegalArgumentException if length = 0, or is not a valid Ethnicity value.
	 * @see Ethnicity
	 */
	public void setEthnicity(String ethnicity)
	{
		_impl.setEthnicity(ethnicity);
	}
	
	/**
	 * Sets the users income.
	 * 
	 * @param income a valid income from Income. null clears previously set parameter.
	 * @throws IllegalArgumentException if length = 0, or is not a valid Income value.
	 * @see Income
	 */
	public void setIncome(String income)
	{
		_impl.setIncome(income);
	}
	
	/**
	 * Sets the users education.
	 * 
	 * @param education a valid education from Education. null clears previously set parameter.
	 * @throws IllegalArgumentException if length = 0, or is not a valid Education value.
	 * @see Education
	 */
	public void setEducation(String education)
	{
		_impl.setEducation(education);
	}
	
	/**
	 * Sets the users date of birth
	 * @param dob a date of birth in the format YYYYMMDD. (i.e. 20100130 for 30th Jan 2010). null clears previously set parameter.
	 * @throws IllegalArgumentException if length != 8.
	 */
	public void setDateOfBirth(String dob)
	{
		_impl.setDateOfBirth(dob);
	}
	
	/**
	 * Sets the users gender sought.
	 * 
	 * @param genderSought a gender sought from GenderSought. null clears previously set parameter.
	 * @throws IllegalArgumentException if length = 0, or is not a valid GenderSought value.
	 * @see GenderSought
	 */
	public void setGenderSought(String genderSought)
	{
		_impl.setGenderSought(genderSought);
	}
	
	/**
	 * Sets the users marital status.
	 * 
	 * @param maritalStatus a marital status from MaritalStatus. null clears previously set parameter.
	 * @throws IllegalArgumentException if length = 0, or is not a valid MaritalStatus value.
	 * @see MaritalStatus
	 */
	public void setMaritalStatus(String maritalStatus)
	{
		_impl.setMaritalStatus(maritalStatus);
	}
	
	/**
	 * Allows manually setting of GPS coordinates.
	 * 
	 * @param latitude latitude
	 * @param longitude longitude
	 */
	public void setGPSCoords(double latitude, double longitude)
	{		
		_impl.setGPSCoords(latitude, longitude);
	}
	
	/**
	 * Sets a keyword string.
	 * 
	 * @param keywordString a keyword string. null clears previously set parameter.
	 * @throws IllegalArgumentException if length = 0.
	 */
	public void setKeywordString(String keywordString)
	{
		_impl.setKeywordString(keywordString);
	}
	
	/**
	 * Sets a query string.
	 * 
	 * @param queryString a query string. null clears previously set parameter.
	 * @throws IllegalArgumentException if length = 0.
	 */
	public void setQueryString(String queryString)
	{
		_impl.setQueryString(queryString);
	}
}
